Tutoriel express pour l’utilisation de github dans le cadre d’un dépôt de publication Rzine
1 Préambule
1.1 Pourquoi utiliser Github dans le cadre de Rzine
Depuis maintenant plusieurs années en SHS on entend beaucoup parler de Git, Github ou encore Gitlab, il s’agit quasiment d’un passage obligé lorsque l’on parle de traitement de la données. Ces outils ont vocation à faciliter le partage et la collaboration autour de projets. Les fonctionnalités proposées permettent notamment le suivi et la comparaison de version et un reviewing efficace.
1.2 Objectif de cette fiche
Si au sein de certaines disciplines, comme notamment en informatique, ce que sont Git et Github et leur fonctionnement est très clair, ça l’est souvent beaucoup moins en science humaine. Nous nous proposons ici d’en réaliser une présentation très succinte et présenter un pas à pas simplifier afin de faciliter la prise en main de ces outils dans le cadre spécifique du dépôt d’une fiche Rzine. Il ne s’agit en aucun cas d’aborder toutes les subtilités et la compléxité de Git.
R ne sera donc ici pas du tout le sujet, et aucune information sur la manière de renseigner une fiche Rzine ne sera donnée. Pour cela, rendez-vous sur la fiche : Référencer une publication sur Rzine
1.3 Glossaire
Ici quelques termes spécifiques à Git qu’il nous a semblé important d’expliciter un minimum.
Bréve Introduction
Git est un logiciel libre dont le premier développement date de 2005 crée par Linus Torvald (auteur du noyau Linux) dont la fonctionnalité est la gestion/contrôle de version1. Git permet le stockage des fichiers mais surtout toutes les modifications effectuées dans le temps. Par ailleurs, Git a été conçus dans l’optique de permettre et faciliter la collaboration entre les individus en intégrant les apports de chacun au projet. Le fonctionnement de Git repose sur des lignes de commande et vous l’aurez compris il s’agit du coeur autour duquel se sont dévellopés les outils comme Github et Gitlab.
Github et Gitlab sont à l’origine des sites webs dont l’objectif est de venir renforcer l’aspect collaboratif de Git en proposant des fonctionnalités supplémentaires. Telles que que la gestion des tickets/issues, les releases, la documentation… Ils offrent également une interface graphique à Git qui permet dans une certaine mesure de s’affranchir des lignes de commande sur lesquelles repose Git.
Github et Gitlab permettent glabalment la même chose. Gitlab est une alternative open source, permettant peut être un usage plus avancé et plus poussé, alors que Github est le site ayant popularisé Git, il s’agit de la référence mondiale et regroupe plusieurs millions d’utilisateurs.
Pas à pas création dépot github
Dans le cadre de ce tutoriel, nous vous proposons de suivre pas à pas le dépot de cette fiche sur un compte github. La démarche se fera à la fois en click-bouton et à l’aide des lignes de commande. Cette fiche a été réalisé via R et un Rmarkdown, dans un projet R enregistré en local.
1.4 Installation de Git
La première étape consiste à installer Git sur votre ordinateur.
Cela se fait très simplement quelque soit le système d’exploitation de votre machine. Il suffit de suivre les instructions parfaitement détaillées en français sur la page d’installation de Git
1.5 Création d’un compte Github
Cette première étape est un passage obligé. Si ce fonctionnement peut faire, à raison, penser à un réseau social rassurez-vous les règles de la propirété intellectuelle sont très claires, et vous choisirez les projets à rendre publics ou privées, ainsi que les collaborateurs à éventuellement inviter.
La création d’un compte se fait de manière tout à fait classique:
- Rendez-vous sur le site de Github
- Cliquez sur sign up en haut à droite
- Remplissez les champs demandés
1.6 Créer un nouveau dépôt Github
Une fois connecté à Github vous arrivez sur la page de votre profil.
Pour créer un dépot2 rendez-vous sur la section Repositories via le bandeau.
Cette page recence tous les répertoires associés à votre compte, si vous venez de vous créer un compte, elle devrait donc être vide, sinon vous retrouverez ici tous vos différents dépôts. Pour en créer un, il suffit de cliquer sur new.
C’est sur cette page à laquelle vous venez d’accéder après avoir cliqué sur new que vous allez véritablement créer votre nouveau dépôts : lui donner un nom, déterminer son statut privé ou public…
Après avoir cliqué sur Create repository vous aurez donc crée avec succès un nouveau dépôt Github. Vous verrez cette nouvelle page s’afficher. Elle vous orientera vers différentes marche à suivre. Par ailleurs, cette page vous fournis en grande partie les lignes de commande et les informations que nous allons utilisé pour remplir votre répertoire.
Tant que vous n’aurez rien importé dans votre dépôt, c’est cette page avec ces informations succintes qui constituera la page d’acceuil de votre dépôt.
1.7 Importer des élements dans votre répertoire Github depuis votre ordinateur
Pour réaliser cet import, nous allons temporairement laissé Github de côté. Vous avez donc réaliser en local votre fiche Rzine, et disposez d’un dossier contenant tous les différents éléments. L’objectif est donc d’importer facilement ce dossier (dans son intégralité) dans votre répertoire. Pour ce faire nous allons utilisé git et ses lignes de commande basique.
Cette procédure fonctionne dans le cadre d’une fiche Rzine, mais fonctionne exactement de la même manière pour n’importe quel autre projet.
1- Il vous faut en premier lieu ouvrir votre terminal ou invite de commande
C’est la façon la plus efficace d’intéragir avec Github depuis votre ordinateur. Cette interface, si on est pas habitué peut effectivement rebuté, mais l’apprentissage pour réaliser certaines opérations basiques se fait rapidement. En revanche, chaque système d’exploitation possède sa propre interface en ligne de commande :
Windows : l’invite de commande. Celle-ci peut être lancée en utilisant la touche Windows et en tapant Invite de commande (ou cmd) avant de sélectionner l’option dans la liste qui apparaît.
- MacOS : le terminal. On le trouvera dans Applications > Utilitaires.
Linux : Généralement, on peut lancer un terminal avec le raccourci clavier Ctrl + Alt + T. Si cela ne fonctionne pas, recherchez Terminal dans les applications ou via les outils de recherche.
Attention sur Linux pour faire un copié-collé dans le terminal il faut utiliser le raccourci ctrl+shift+c pour collé et ctrl+shift+v pour collé.
Voici à quoi ressemble un terminal :
2- Nous allons maintenant nous placer dans le dossier au sein duquel vous avez enregistré votre projet que vous souhaitez importer. Pour ce faire nous utiliserons cette ligne de commande
cd "chemin/vers/votre/dossier"
Il faudra bien sur remplacer le chemin entre "" par le chemin correspondant à votre dossier sur votre ordinateur.
3- Il faut ensuite lancer Git :
git init
Cette commande permet d’initialiser Git dans le dossier au sein duquel vous vous trouvez, cela implique que toutes les opérations que vous réaliserez avec Git dans ce dossier seront sauvegardés.
git config --global user.email "Vous@exemple.com" git config --global user.name "Votre Nom"
4- Une fois git initialisé, il faut lui indiquer l’URL du dépôt Github au sein duquel vous souhaitez importer vos fichier et dossier.
git remote add origin https://github.com/LeCampionG/github_fiche_rzine.git
Cette url est celle indiqué dans la barre d’adresse de votre navigateur lorsque vous êtes connecté à Github et dans votre dépôt. Elle est également indiqué dans les premières informations affichées lorsque vous avez créée votre dépôt.
5- Nous indiquons maintenant ce que nous souhaitons envoyer, importer dans notre dépôt
Cela se fait en plusieurs étape. D’abord spécifier les fichiers à envoyer.
Pour importer l’intégralité du dossier nous utiliserons la commande :
git add --all
Si vous souhaitez envoyer un fichier particulier, par exemple notre rmd nous écririons : git add rzine_tuto_github.Rmd
Une fois avoir précisé les éléments à transfèrer nous allons devoir réaliser un commit3. Avec cette commande nous allons réalisé un instantané (au sens photographique) des fichiers sur lesquels nous travaillons. Il s’agit en fait d’une sauvegarde à un instant “t” des différents éléments du dossier.
git commit -m "1er import des fichiers"
-m "un_texte" permet simplement d’expliciter l’action, en l’associant à un message, une description.
6- La dernière étape consiste à rendre tout cela visible et accessible, on parle de pusher4 les fichiers :
git push -u origin master
master correspond à l’endroit où nous allons envoyé nos fichiers.
Pour valider votre import, il faudra fournir votre identifiant et votre mot de passe
Votre dépôt contient désormais les fichiers que vous aviez en local sur votre ordinateur.
Si intéragir avec votre terminal ou invite de commande ne vous convient pas, il existe également des interfaces graphiques pour Git qui permettent globalement la même chose, mais vous devrez malgré tout utiliser les lignes de commande avec ces applications.
Les “Issues” Github
Les issues Github correspondent à un espace d’échange autour de votre projet. C’est un espace ouvert à tous si votre dépôt est public ou seleument à vous-même ou aux personnes auxquelles vous aurez donné accès dans le cas d’un dépôt privé.
La plupart du temps les issues servent à faire remonter des bugs, signaler des idées de développement, d’améliorations…
Plus que de simple commentaires, il s’agit d’espaces d’échanges à l’image de forum. Vous pourrez répondre, commenter, ainsi que maintenir ouvert ou clôturer l’issue.
Pour ouvrir une issue, il faut d’abord se rendre dans la section correspondante via le bandeau.
Cette page va recenser toutes les issues associées à votre projet. Pour créer et ouvrir une issue il suffit simplement de cliquer sur New issue.
Vous pourrez donner un titre à votre issue, tagger une personnes, donner une étiquette… Une fois rédigé, cliquez sur Submit new issue.
Pour répondre, modifier, clôturer (ou ré-ouvrir) une issue, il suffit de cliquer dessus et réaliser une de ces actions.
Branche et Pull requests
1.8 Les branches
Git et Github permettent de faire des branches5 Cela s’avère très utile lorsque l’on travaille à plusieurs ou que des corrections sont nécessaires.
Dans Gitub, la création de branches peut se faire facilement. Depuis l’acceuil de votre dépôt (onglet <> code) cliquez sur le bouton encadré en rouge, dans l’image ci-dessous. Ce bouton permet entre autre de créer des branches.
Un menu déroulant apparait, pour créer une branche il suffit d’écrire son nom puis de cliquer sur Create branch.
Cet onget vous indiquera dans quelle branche vous vous trouvez mais également de naviguer entre vos branches.
En procédant de cette manière, les branches créee seront des copies des branches depuis lesquelles vous les avez produites. Cela suppose que s’il y a des modification à faire il faut les faire depuis Github ou supprimer un fichier et le ré-importer dans la branche. Ce n’est pas toujours le plus efficace.
La même chose est possible en ligne de commande, et ceux de manière plus optimiser (même si, nous aborderons pas ici toute la compléxité et les possibilités de la création de branche avec les fonctions Git).
Pour faciliter la compréhension du principe prenons l’exemple de notre fiche Rzine. Nous avons déposer dans notre dépôt Github une première version de nos travaux. Nous souhaitons la faire relire par un collègue, ou y apporter nous même des modifications sans toutefois écraser notre première version. Nous allons donc opérer les différentes modifications en local sur notre ordinateur. Une fois satisfait, nous allons créer une branche au sein de laquelle nous allons importé nos fichiers modifiés sans écrasé nos premiers travaux. Le très grand intérêt à cela c’est que nous pourrons par la suite comparer les deux branches et éventuelement les fusionner.
Commencez par vous placer dans le bon répertoire. Nous retournous dans notre dossier :
cd "/mnt/9A8C6DB98C6D9115/gregoire/Rzine/tuto_github"
Pour créer une nouvelle branche il suffit de d’écrire :
git checkout -b correction
Nous avons donc ici créée et basculé vers une nouvelle branche appelée correction.
Et nous pouvons, de la même manière que nous l’avons fait pour la branche principale de notre dépôt, importer un fichier ou des dossiers dans cette branche nouvellement créée.
Attention, il est nécessaire d’indiquer à Git quel fichiers ont été retravaillés
git add rzine_tuto_github.Rmd
Pour importer tous les éléments du dossier dans lequel nous nous trouvons : git add --all
La commande git status peut être très pratique pour avoir un aperçu des fichiers qui ont subi des modifications.
Comme précédemment, il faut réaliser un commit, qui permetra notamment de voir et prendre en compte toutes les modifiations qui ont été faites
git commit -m 'fichier sur lequel réaliser modifications'
Et enfin, on envoit effectivement sur notre branche de notre dépôt :
git push origin correction
Pour retourner sur une autre branche, par exemple la branche master
git checkout master
1.9 Pull requests
Avec la création de branches vous pouvez modifier comme vous le souhaitez un fichier tout en le conservant intact dans une autre branche. Cependant, une fois les corrections, les modifications… terminées il peut être utile de comparer les différents élément et fusionner les fichiers modifiés. On peut alors réaliser une pull requests.
Github propose une interface graphique intéressante pour réaliser cette opération (elle est bien évidemment aussi faisable en ligne de commande). Pour se faire utilisez le bandeau et rendez-vous dans la section Pull requests.
Pour réaliser une pull request il faut au moins une autre branche à fusionner, et que les deux branches aient au moin sun élément dissemblable.
Cliquez sur New pull request pour lancer une nouvelle comparaison:
Il faut désormais choisir les deux branches à comparer :
Une fois fait, vous verrez les différences éventuelles entre vos deux branches : les modifications des fichiers similaires, les fichiers présents dans la 2ème branche mais pas la première…
Si cela vous convient, cliquez sur le bouton Create pull request.
Vous pouvez ensuite commenter, décrire votre demande et la soumettre en cliquant sur Create pull request.
Vous avez donc fait une demande qui apparaitra dans votre section Pull requests.
Vous pouvez echanger de la manière qu’avec les issues, mais surtout visualiser les ce qui sera fusionner. Si cela vous convient vous pouvez accepter les modifications vous pouvez cliquer sur Merge pull request ou au contraire refuser et cliquer sur Close pull request.
Les deux branches seront alors fusionner.
Liste non exhaustive des commandes Git pouvant être utiles
git init : Initialise un nouveau dépôt Git. S’est seulement après avoir entré cette commande que vous pourrez commencer à travailler avec Git.
git config : raccourci de “configurer,” cette commande est particulièrement utile quand vous paramétrez Git pour la première fois.
git help : Permet d’afficher les 21 commandes les plus courantes de Git. Vous pouvez aussi être plus spécifique et saisir par exemple git help init ou tout autre terme pour voir comment utiliser et configurer une commande spécifique Git.
git status : Vérifie le statut de votre dépôt. Voir quels fichiers sont à l’intérieur, quelles sont les modifications à commiter, et sur quelle branche du dépôt vous êtes en train de travailler.
git add : Cette commande n’ajoute pas de nouveaux fichiers dans votre dépôt. Elle “porte” de nouveaux fichiers à l’attention de Git. Après avoir ajouté des fichiers, ils sont inclus dans les « instantanés » du dépôt Git.
git commit : Une des commandes les plus importante de Git. Après avoir effectué toute sorte de modification, vous entrez ça afin de prendre un “instantané” du dépôt. Instantané au sens de photgraphie et donc de sauvegarde.
git push : Si vous travaillez sur votre ordinateur local, et voulez que vos commits soient visibles aussi en ligne sur Github, vous “push”ez les modifications vers Github avec cette commande. Se sont les fichiers portés à l’attention de Git avec git add qui seront “push”ez
git branch : Cette commande vous permet de construire une nouvelle branche, ou une chronologie des commits, des modifications, des ajouts de fichiers…
git checkout : Permet littéralement de vérifier un dépôt dans lequel vous n’êtes pas. C’est une commande de navigation qui vous permet de vous déplacer vers le répertoire que vous voulez vérifier et au sein duquel vous souhaitez travailler. Permet aussi la création d’une branche.
git merge : Lorsque vous avez fini de travailler sur une branche, vous pouvez fusionner vos modifications vers la branche master, qui est visible pour tous les collaborateurs.
git pull : Permet un export en local de la version la plus à jour de votre dépôt.
La gestion ou le conrôle de version renvoie à des pratiques dont l’objectif est de gérer les changement apporté à un fichier (généralement plutôt du code) au fil du temps. Par exemple dans un document word, chaque sauvegarde écrase la précédente, on peut aussi enregistrer une nouvelle version du document qui devient alors un autre fichier complétement indépendant. Dans les systèmes de contrôle de version on va conservé le même fichier mais garder trace de tous les changement réalisé, comme si on prenait et stocké une “photo”, un “instantané” du fichier à chaque changement fichier↩
Le dépôt/répertoire/repo/repostory est l’espace où vous aller stocker vos fichiers. Il peut être local (le dossier au sein duquel avez enregistré votre fiche Rzine) ou en ligne (l’espace sur Github où vous allez importé vos fichiers). Vous pouvez stocker n’importe quel type de fichier au sein d’un dépôt.↩
Le commit est l’enregistrement des changements effectué sur un fichier. Il s’agit de l’“instantané”, du point de sauvegarde des changement qui ont été réalisé. C’est sur le commit que repose complétement le système de contrôle de version et donc plus largement les outils comme Git et Github.↩
Push/“Pusher” est le fait d’envoyer les commits (modifications réalisés) sur le dépôt est donc de les rendre visibles.↩
Une branche est une ramification indépendante de vote dépôt source. Elle permets donc de modifier en parallèle les fichiers ou la structure du dépôts sans affecter les autres branches. C’est extrêment utile d’autant qu’elles peuvent ensuite être re-fusionner.↩